home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UTIL / MEMORY / OLD / MEM208SRC / FSLib / doc / SwiDoc < prev   
Text File  |  1993-09-08  |  4KB  |  97 lines
  1. _swi & _swix
  2. ------------
  3.  
  4. These functions provide a generic method of calling RISC OS SWIs from C.
  5. They are the preferred method of calling SWIs.
  6.  
  7. Two functions are provided _swi, for calling SWIs without setting the X bit
  8. and _swix which sets the X bit before calling the SWI.
  9.  
  10. The definitions for these functions are
  11.  
  12. extern int _swi(int swi_no, unsigned int mask, ...);
  13.  
  14. extern int _swix(int swi_no, unsigned int mask, ...);
  15.  
  16. swi_no is the number of the SWI to be called. This should never have the X
  17. bit set.
  18.  
  19. mask is a word containing an input and output register mask, a return register,
  20. and a block parameter register.
  21.  
  22. The arrangement of mask is as follows:
  23.  
  24. Bits 0 -  9:  Set if R(N) is passed to the SWI.
  25. Bits 22 - 31: Set if R(31-N) is output from the SWI (ie bit 31
  26.               corresponds to R0, bit 22 corresponds to R9).
  27. Bit 21:       Set if the PC (including the flags) is to be output.
  28. Bits 16 - 19: Register no. to be returned from a _swi call. This is only
  29.               applicable to _swi as _swix always returns either 0 or an error
  30.               pointer.
  31. Bit 11:       Set if a local block parameter is to be passed to the SWI
  32. Bits 12 - 15: Register number for local block parameter if bit 11 set.
  33.  
  34. If a register is specified as a return register (bits 16-19) it must not
  35. also be specified as an output register in the output register mask (bits
  36. 22-31).
  37.  
  38. If a register is specified as a local block parameter register it must not
  39. also be specified as an input register in the input register mask (bits
  40. 0-9).
  41.  
  42. If the PC is specified as a return register (ie bits 16-19 = 15) or as an
  43. output registers (bit 21 = 1) the value returned will contain the flags in
  44. bits 28 to 31 (28 = V, 29 = C, 30 = Z, 31 = N).
  45.  
  46. The remainder of the variadic arguments are as follows (in order):
  47.  
  48. The word value of each input register in order from 0 to 9 as specified by
  49. bits 0 to 9 of the mask.
  50.  
  51. The address of a word to be written for each output register in order from 0
  52. to 9 as specified by bits 31 downto 22 of the mask.
  53.  
  54. The address of a word to be written with the PC value on exit from the SWI
  55. if bit 21 of the register mask is set.
  56.  
  57. If bit 11 is set the remainder of the arguments are placed in order in a
  58. parameter block and the address of the parameter block is passed to the SWI
  59. in the register specified by bits 12-15.
  60.  
  61. The functions are declared in the header swis.h along with some macros for
  62. constructing masks and a complete list of system SWI definitions.
  63.  
  64. The macros are as follows:
  65.  
  66. _IN(n)       - Specifies that R(n) is used on input
  67. _OUT(n)      - Specifies that R(n) is output
  68. _BLOCK(n)    - Specifies that R(n) is a block parameter
  69. _RETURN(n)   - Specifies that R(n) is returned from _swi.
  70.  
  71. The values of the macros should be ORed together to produce the value for
  72. the mask.
  73.  
  74. The following constants are defined
  75.  
  76. _FLAGS       - the register containing the flags (currently 15)
  77. _C           - mask for the C bit in _FLAGS
  78. _Z           - mask for the Z bit in _FLAGS
  79. _N           - mask for the N bit in _FLAGS
  80.  
  81. Please use these constants as they may change on ARM 600.
  82.  
  83. Example calls:
  84.  
  85.     _swi(OS_NewLine, 0);   /* Must specify 0 register mask */
  86.  
  87.     _swi(OS_Write0, _IN(0), "Hello, World");
  88.  
  89.     task_handle = _swi(Wimp_Initialise, _IN(0)|_IN(1)|_IN(2)|_RETURN(1),
  90.                        300, *(int *)"TASK", "Test");
  91.  
  92.     e = _swix(Wimp_LoadTemplate, _IN(1)|_IN(2)|_IN(3)|_IN(4)|_IN(5)|_IN(6)|_OUT(2)|_OUT(6),
  93.               template_buffer, workspace, workspace_end, -1, "MyWind", next,
  94.               &workspace_end, &next);
  95.  
  96.     e = _swix(Wimp_SetExtent, _IN(0)|_BLOCK(1), w, minx, miny, maxx, maxy);
  97.